/**
 * Copyright 2011 Honeywell Federal Manufacturing & Technologies, LLC. This material was produced under U.S. Government
 * contract DE-ACO4-01AL66850, Honeywell Federal Manufacturing & Technologies, LLC, (FM&T) with the U. S. Department of
 * Energy for the operation of the Kansas City Plant . The U.S. Government has rights to use, reproduce, and distribute
 * this software.  NEITHER THE GOVERNMENT NOR Honeywell Federal Manufacturing & Technologies, LLC, MAKES ANY WARRANTY,
 * EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
 * derivative works, such modified software should be clearly marked, so as not to confuse it with the version available
 * from FM&T.
 *
 * Additionally, this program is free software; you can redistribute it and/or modify it under the terms of the GNU
 * General Public License Version 3 published by the Free Software Foundation. Accordingly, this program is distributed in
 * the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with this library.
 * If not, see http://www.gnu.org/licenses/.
 */
package org.braintrain.services;

import org.braintrain.domain.Module;
import org.braintrain.domain.Navigation;

import java.util.List;

/**
 * The Navigation Service.  This Interface outlines the various functionality
 * commonly used when dealing with Navigation.
 * 
 * @author John Ericksen
 *
 */
public interface NavigationService {

    /**
     * Inserts a new Navigation into the navigation chain.  This links the given "nav"
     * along the getDeltaNext() path to be added to the getNext() path when the module is 
     * released.
     * @param current
     * @param nav
     * @return
     */
    Navigation insertNavigation(Navigation current, Navigation nav);
    
    /**
     * Returns a List of Navigations.  This function finds all the "Main" pages
     * that exist in the module (where mainNavigaton = true) and resolves the chain of navigations
     * after the root element that exist along the getNext() links.
     * @param module
     * @return
     */
    List<Navigation> getMainNavigationChain(Module module);
    
    /**
     * 
     * Returns a List of Navigations.  This function finds all the "Main" pages
     * that exist in the module (where mainNavigaton = true) and resolves the chain of navigations
     * after the root element that exist along the getDeltaNext() links.  Also, deleted items not
     * along the getDeltaNext() path that exist along the getNext() path are added in their respective
     * places.
     * @param module
     * @param includeDeleted
     * @return
     */
    List<Navigation> getMainDeltaNavigationChain(Module module, boolean includeDeleted);

    /**
     * Performs a swap with the getDeltaNext() item.  Also, sets the moved flag
     * to true.
     * @param id
     */
    void saveMoveNavigationForward(Long id);

    /**
     * Performs a swap with the getDeltaPrev() item.  Also, sets the moved flag
     * to true.
     * @param id
     */
    void saveMoveNavigationBack(Long id);

    /**
     * Delete a navigation with the given Id.  This consists of 
     * completely removing the "pending" changes to the navigation item
     * as well as putting the "released" navigation (if it exists) into a
     * deleted NavigationState.  This "deleted" Navigation will be deleted when
     * the Module is released. 
     * @param id
     */    
    void deleteNavigation(Long id);

    /**
     * Returns a List of List of Navigations.  This function finds all the "pending" (if delta = true) "link/popup" pages
     * that exist in the module (where mainNavigaton = false) and resolves the chain of navigations
     * after the root elements.  Also, deleted items not
     * along the getDeltaNext() path that exist along the getNext() path are added in their respective
     * places (if includeDeletes = true).
     * @param module
     */
    List<List<Navigation>> getLinkedChains(Module module, boolean delta, boolean includeDeletes);

    /**
     * Saves and releases a given module.  This consists of copying the pending Navigation
     * into the getNext() and getPrev() chain as well as deleting "deleted" or unlinked
     * Navigators.  Of course, Tests are a special case because they cannot be deleted
     * per the TestLog.
     * @param module
     */
    void saveRelease(Module module);

    /**
     * Removes all changes from the chain of getDeltaNext().  This can be disasterous if
     * used at a bad time (like when a module hasn't been released yet.
     * 
     * @param module
     */
    //public void saveSyncDeltaWithReleased(Module module);

    /**
     * Swaps two navigation elements using the robust swap method
     * (verses the swapWithNext function that swaps two elements next to each other)
     * @param released
     * @param edited
     */
    void saveSwapNavigation(Navigation released, Navigation edited);

    /**
     * As long as there is a pending change to a released content and
     * the pending navigation points to the released navigation, this
     * function will delete the current changes and swap back in the released
     * changes.
     * @param navigation
     */
    void saveRollBackDeltaNavigation(Long navigationId);
    
    /**
     * Undelete a given Navigation.  This reconnects the navigation to its previous 
     * non-deleted element.  If one don't exist, then reconnect it to the next non-deleted
     * element.  Of course, the respective deltaNext is null.
     * @param navigation
     */
    void saveUndeleteNavigation(Long navigationId);

    //public void saveConversion();
}
